﻿/*  
	========================================================================
	 awzBoxes Library
	
	 Homepage: http://www.awzhome.de/
	========================================================================
	
	This Source Code Form is subject to the terms of the Mozilla Public
	License, v. 2.0. If a copy of the MPL was not distributed with this
	file, You can obtain one at http://mozilla.org/MPL/2.0/.
   
	The Original Code is code of awzBoxes Library.

	The Initial Developer of the Original Code is Andreas Weizel.
	Portions created by the Initial Developer are
	Copyright (C) 2011-2012 Andreas Weizel. All Rights Reserved.
	
	Contributor(s): (none)
	
	========================================================================
*/

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace AWZhome.awzBoxes
{
	/// <summary>
	/// Interface for layout storage providers allowing awzBoxes library
	/// to save and restore layout information for <see cref="AWZhome.awzBoxes.BoxItem"/>s.
	/// </summary>
	public interface ILayoutStorageProvider
	{
		/// <summary>
		/// Reads a configuration string for a <see cref="AWZhome.awzBoxes.BoxItem"/>.
		/// </summary>
		/// <param name="boxItemName">Name of the <see cref="AWZhome.awzBoxes.BoxItem"/>.</param>
		/// <returns>Layout configuration string for the <see cref="AWZhome.awzBoxes.BoxItem"/>.</returns>
		string GetBoxItemConfiguration(string boxItemName);

		/// <summary>
		/// Saves a configuration string <see cref="AWZhome.awzBoxes.BoxItem"/>.
		/// </summary>
		/// <param name="boxItemName">Name of the <see cref="AWZhome.awzBoxes.BoxItem"/>.</param>
		/// <param name="configuration">
		/// Layout configuration string for the
		/// <see cref="AWZhome.awzBoxes.BoxItem"/>.
		/// </param>
		void SetBoxItemConfiguration(string boxItemName, string configuration);

		/// <summary>
		/// Reads the list of <see cref="AWZhome.awzBoxes.BoxItem"/> names, that
		/// have to be restored when application is relaunched.
		/// </summary>
		/// <returns>Array of names.</returns>
		string[] GetLastOpenBoxItems();

		/// <summary>
		/// Saves a list of names of open <see cref="AWZhome.awzBoxes.BoxItem"/>
		/// objects to be able to restore them on next application restart.
		/// </summary>
		/// <param name="openBoxItems">Array of <see cref="AWZhome.awzBoxes.BoxItem"/> names.</param>
		void SaveLastOpenBoxItems(string[] openBoxItems);

		/// <summary>
		/// Restores a <see cref="AWZhome.awzBoxes.BoxItem"/> object from its name.
		/// </summary>
		/// <param name="name">String name of the <see cref="AWZhome.awzBoxes.BoxItem"/>.</param>
		/// <returns>Restored <see cref="AWZhome.awzBoxes.BoxItem"/> object or <c>null</c>,
		/// if the item should not be restored.</returns>
		/// <remarks>
		/// This method gives the user of awzBoxes the possibility to control which
		/// box items are restored and which content should be shown there.
		/// </remarks>
		BoxItem RestoreBoxItem(string name);

		/// <summary>
		/// Sets a general configuration value.
		/// </summary>
		/// <param name="key">String-based key of the setting.</param>
		/// <param name="value">Setting value.</param>
		void SetGeneralConfiguration(string key, string value);

		/// <summary>
		/// Reads a general configuration value.
		/// </summary>
		/// <param name="key">String-based key of the setting.</param>
		/// <returns>Setting value.</returns>
		string GetGeneralConfiguration(string key);
	}
}
